Neo4j
Summary
This document covers the information to gather from Neo4j in order to configure a Qarbine data service. The data service will use the Qarbine Neo4j driver. You can define multiple data services that access the same Neo4j endpoint though with varying credentials. Once a data service is defined, you can manage which Qarbine principals have access to it and its associated Neo4j data. A Qarbine administrator has visibility to all data services.
Several example catalog components use a data service named “Neo4j”. The “Neo4j Movies AI” data service is pre-configured.
Overview
Neo4j is a popular graph database. Information of the offering can be found at
https://neo4j.com/cloud/platform/aura-graph-database/.
Qarbine supports direct, native Neo4j Cypher and Gremlin queries. Direct Cypher querying is the only real way to access the full power of Neo4j. Here is a sample Cypher query for the sample Neo4j movie database.
MATCH (person: Person)-[relatedTo]-(movie: Movie {title: "The Matrix"})
RETURN * order by person.name
The result is a list of objects with a rich data structure containing Person, Movie, and relationship properties. Such structures are not handled naturally by legacy SQL tools which require homogeneous tabular data.
Neo4j Configuration
Information on Neo4j users can be found at https://neo4j.com/docs/cypher-manual/current/access-control/manage-users/
Information on various database roles can be found at
https://neo4j.com/docs/cypher-manual/current/access-control/manage-roles/
Sign on to your Neo4j console. A sample starting URL is https://console.neo4j.io/
Make sure your instance is
Click on
On that page the URL below will be used for the Qarbine Data Service’s server URL.
Confirm the authentication type shown below and note the user and password values.
For personal development purposes the user name and password values will be part of the Data Service options. For broader interactions a read only account should be used.
To confirm access click
Defining a Read Only User
Click the Databases link shown below.
Confirm the status is
For Aura, activate the database area page.
Choose the system database.
You can also run the statement below
Click
or
To see all users run the command as shown below
Use the general statements below to create a read only user.
CREATE USER guest SET PLAINTEXT PASSWORD 'somePassword'
GRANT ROLE reader TO guest
Qarbine Configuration
Compute Node Preparation
Determine which compute node service endpoint you want to run this data access from. That URL will go into the Data Service’s Compute URL field. Its form is “https://domain:port/dispatch”. A sample is shown below.
The port number corresponds to a named service endpoint configured on the given target host. For example, the primary compute node usually is set to have a ‘main’ service. That service’s configuration is defined in the ˜./qarbine.service/config/service.main.json file. Inside that file the following driver entry is required
. . .
"./driver/neo4jDriver.js"
]
The relevant configuration file name for non primary (main) Qarbine compute nodes is service.NAME.json. Remember to have well formed JSON syntax or a startup error is likely to occur. If you end up adding that entry then restart the service via the general command line syntax
pm2 restart <service>
For example,
pm2 restart main
or simply
pm2 restart all
Data Service Definition
The Qarbine data service requires:
- Neo4j connect URL and
- Neo4j user and password.
Within the Qarbine Administration tool navigate to Data Services
Click
Enter the name, description, and compute node endpoint URL.
Choose
For the server template enter the Neo4j Connect URL.
For the server options enter
password="THE_PASSWORD"
These values are both case sensitive. Note that the Neo4j session mode is always set to “read access only”. In the data options you may specify
fetchSize=1000
You can reference environment variables using the syntax %NAME%. Any strings should be quoted and the key\value pairs separated by commas.
You may specify a default database within the “Database” field. If not specified here then ‘neo4j’ is used. In the Neo4j console you can switch to the system database.
and run the query below to get a list of databases.
After you have entered the above information save the data service by clicking 
.
Next, test the settings by clicking on the icon noted below.
You should see the following general dialog
The data service will be known at the next log on time. Next, see the Neo4j query interaction and any tutorial for information on interacting with Neo4j from Qarbine.
NOTE - Some example Neo4j components reference the data service named “Neo4j”.
Online Neo4j Movies Database
There is an online Neo4j database service providing movie related data including embeddings. For details see https://github.com/neo4j-graph-examples/recommendations?tab=readme-ov-file
The Qarbine components in the “examples/Neo4j/Movie AI” folder use the following data service definition.
The data sources using vector indexes require a Qarbine AI Assistant using Open AI to be defined. Configuring AI Assistants is discussed in that particular document.
NOTE - Some example Neo4j components reference the data service named “Neo4j movies AI”.
Troubleshooting
If the following error occurs then verify the Data Service definition and that the intended database is operating at the given location. Another team member such as a DBA may be responsible for this activity.
Your instance may also be paused. To check, open the Neo4j console at https://console.neo4j.io/ and navigate to your instance.
If this is the case then resume the instance by clicking the right arrow in the left hand corner.
The status will change to
Wait for it to become
Cross reference the Connection URI matches the data service’s server template.
